Guía Maestra: Generador de Planes Académicos IA

1. Visión General del Proyecto

El objetivo es construir una herramienta web dedicada y avanzada que utilice un modelo de IA para generar planes académicos detallados (charlas) de 2.5 horas de duración para los subtemas de un curso. La herramienta debe ser contextual, utilizando no solo una instrucción directa del usuario, sino también información estructural del curso (nombres, descripciones, objetivos) para producir resultados de alta calidad. El sistema debe ser robusto, seguro y ofrecer una experiencia de usuario clara y controlada.

2. Arquitectura de la Solución

La solución se desacopla de la vista principal del curso para existir como una herramienta independiente, mejorando la mantenibilidad y permitiendo una interfaz más rica. Los componentes son:

Punto de Acceso: Un enlace en la vista de curso (`ver_curso_o_ppp_ia.php`) que dirige al usuario a la nueva herramienta, pasando el ID del subtema.
Interfaz de Usuario (Frontend): Una nueva página dedicada, `generador_plan_academico.php`, que servirá como el panel de control central para esta funcionalidad.
Agente IA (Backend): Un nuevo script PHP, `avi/chat_charla_ia.php`, cuya única función es recibir un ID, recopilar todo el contexto, y generar el plan académico.
Microservicios de Guardado (Backend): Scripts pequeños y dedicados (ej. `ajax_guardar_prompt.php`, `ajax_guardar_charla.php`) para manejar las operaciones de escritura en la base de datos de forma segura.

3. Requisitos de Base de Datos

Este es el prerrequisito fundamental. La tabla subtemas_curso debe ser modificada para almacenar la nueva información.

Acción Obligatoria: Un desarrollador debe ejecutar las siguientes sentencias SQL en la base de datos antes de proceder con cualquier desarrollo de código. La ausencia de estos campos causará fallos en el sistema.

ALTER TABLE `subtemas_curso`
ADD COLUMN `prompt` TEXT NULL DEFAULT NULL COMMENT 'Instrucción específica del usuario para la IA' AFTER `valor_hora`,
ADD COLUMN `charla` LONGTEXT NULL DEFAULT NULL COMMENT 'Plan de charla generado por la IA' AFTER `prompt`,
ADD COLUMN `token_count` INT(11) NULL DEFAULT 0 COMMENT 'Contador de palabras/tokens del prompt' AFTER `charla`;

4. Diseño de Interfaz y Experiencia de Usuario (UI/UX)

La nueva página generador_plan_academico.php será la interfaz principal. Recibirá un `id` de subtema por URL (ej. ?id=123) y se estructurará de la siguiente manera:

Encabezado de Contexto

Una sección superior no editable que muestra la jerarquía para que el usuario siempre esté ubicado:

Curso: [Nombre del Curso Obtenido de la BD]
Tema: [Nombre del Tema Padre Obtenido de la BD]
Subtema: [Nombre del Subtema Actual Obtenido de la BD]

Panel de Control del Prompt

Un área de dos columnas que permite al usuario construir la instrucción perfecta para la IA.

Prompt Sugerido por el Sistema

Un <textarea> editable que se rellena al cargar la página con todo el contexto concatenado (descripciones, objetivos, etc.). El usuario puede refinar esta sugerencia.

Contador: Debajo, un contador de palabras se actualizará en tiempo real: <span id="word_count">0</span> palabras (tokens aprox.).

Prompt Final (Para Guardar)

Un <textarea> que muestra el `prompt` actualmente guardado en la base de datos. El usuario puede copiar la sugerencia de la izquierda aquí, o escribir una desde cero.

Botón "Guardar Prompt": Al hacer clic, se guardará el contenido de este `textarea` en la base de datos. Si el campo ya tenía contenido, un `confirm()` de JavaScript preguntará: "¿Desea sobrescribir el prompt existente?".

Panel de Generación

Un botón central "Generar Plan de Charla con el Prompt Guardado". Este botón estará deshabilitado hasta que se guarde un `prompt` en la columna derecha, asegurando que solo se use una instrucción definitiva.

Panel de Resultado

Un <textarea> grande, de solo lectura, que mostrará el plan de charla generado por la IA. Al cargar la página, mostrará el contenido del campo charla si ya existe. Contará con un botón "Guardar Plan Definitivo" para persistir el resultado en la base de datos.

5. Flujo Lógico de Datos y Backend

El flujo de datos está diseñado para ser seguro y lógico, separando la lectura, la generación y la escritura.

Carga de Página (`generador_plan_academico.php`): Al cargar, el script PHP ejecuta una consulta SQL compleja con `JOIN`s para obtener todos los datos de contexto (nombres de curso/tema/subtema, y los contenidos de los campos `prompt`, `charla`, descripciones, objetivos, etc.) y los muestra en la interfaz.
Generación del Plan (`avi/chat_charla_ia.php`): Al presionar "Generar Plan", el JavaScript solo envía el `subtema_id` a este script. El backend vuelve a consultar la BD para obtener el `prompt` guardado y todo el contexto, construye el `prompt` final para la IA, lo envía a Google y devuelve únicamente el texto del plan generado.
Guardado del Plan (`ajax_guardar_plan.php`): Al presionar "Guardar Plan Definitivo", el JavaScript envía el `subtema_id` y el contenido del `textarea` a este script, cuya única función es ejecutar una sentencia `UPDATE` segura para guardar los datos en el campo `charla`.

Consejo de Desarrollo: Usar scripts pequeños y dedicados para las acciones de guardado (microservicios) es una práctica excelente que mejora la seguridad y la claridad del código.

6. Flujo de Uso por el Usuario

Desde la perspectiva del usuario, el proceso es intuitivo y le otorga control total.

El usuario navega a ver_curso_o_ppp_ia.php y hace clic en el nuevo botón "Generar Plan" de un subtema.
Es redirigido a generador_plan_academico.php, donde ve toda la información de contexto.
Revisa el "Prompt Sugerido", lo edita si es necesario, y lo pasa al panel de "Prompt Final".
Hace clic en "Guardar Prompt". El sistema le advierte si está sobrescribiendo.
El botón "Generar Plan de Charla" se habilita. El usuario hace clic. Un indicador de carga aparece.
El resultado de la IA aparece en el panel "Plan de Charla Generado".
El usuario puede editar el plan manualmente si lo desea.
Finalmente, hace clic en "Guardar Plan Definitivo" para almacenar el resultado final.

7. Consideraciones Finales y Buenas Prácticas

Seguridad: Todas las operaciones de escritura en la base de datos (`UPDATE`, `INSERT`) deben usar **sentencias preparadas** (prepared statements) para prevenir inyecciones SQL.

Gestión de la API Key: La clave de la API de Google debe permanecer siempre en el lado del servidor (archivos PHP) y nunca ser expuesta en el código JavaScript del lado del cliente. Debe ser tratada como una contraseña.

Experiencia de Usuario: Es fundamental proporcionar retroalimentación visual al usuario durante las operaciones que toman tiempo (como la llamada a la IA). Mostrar y ocultar indicadores de carga (spinners) en los botones es una práctica excelente.